@datacamp/waffles-tokens

Tokens

Usage documentation is available at Waffles tokens documentation. It is possible to import tokens either with import tokens from '@datacamp/waffles-tokens' or individual groups with import { colors } from '@datacamp/waffles-tokens'. Thanks to types definitions tokens auto-completion is supported. Other legacy tokens could be imported from @datacamp/waffles-tokens/lib/name-of-legacy-tokens-file.

This package contains all the design tokens used across Waffles, and also the build methods to generate exposed files with these values.

Structure

New tokens

The new tokens are generated from base-tokens.json. The structure of that file is compatible with Figma Tokens plugin. In the first build step regular JS file (ES module with explicit and default exports) is generated with build:new-tokens script, assuming lib directory already exists. It serves as a base for transpiling both ESM and CJS modules (with appropriate build:cjs and build:esm scripts). Last step is to generate TS typings with build:types.

Legacy tokens

The legacy tokens are for now kept for backward compatibility reasons. All tokens are stored in the /properties directory as json files. On build, these are deep merged and augmented with the transforms. This full data structure is then passed to the formatters to output different files. This is all orchestrated using Style Dictionary and controlled with the buildLegacyTokens.js file.

Outputs

• tokens.esm.js is the main exported tokens file.
• tokens.d.ts are autogenerated TS types definitions.
• core-tokens.json is the legacy tokens file.
• future-tokens.json is the legacy tokens file, used internally by most React components.
• variables.scss contains the same data as the core-tokens file but exposed as scss variables. This is used in to generate utility classes and stylesheets in other packages.

Migration guide (v1 -> v2)

Tokens has been updated to stay in line with Design Guidelines and to be compatible with Figma Tokens plugin.

Deprecated tokens groups

• 🚨 spatial group is deprecated
  • use tokens from sizing, spacing, and zIndex groups
• 🚨 border group is deprecated
  • use tokens from borderRadius group
• 🚨 animation group is deprecated

Completely new tokens groups

• 🟢 new group sizing
• 🟢 new group spacing
• 🟢 new group borderWidth
• 🟢 new group opacity
• 🟢 new group zIndex
• 🟢 new group borderRadius
  • 🚨 border.radius -> borderRadius.medium
  • 🟢 new circle border radius token

Updated tokens groups

• 🔄 changes in colors group:
  • 🟢 new brand colors brandFacebook, brandTwitter, brandGoogle, brandLinkedIn
  • 🟢 new text colors navySubtleTextOnDark, navySubtleTextOnLight
  • 🟢 new greyDark color
  • 🚨 navyText -> navy
  • 🚨 greenText -> greenDarkText
  • 🚨 redText -> redDarkText
  • 🚨 orangeText -> orangeDarkText
  • 🚨 yellowText -> yellowDarkText
  • 🚨 blueText -> blueDarkText
  • 🚨 purpleText -> purpleDarkText
  • 🚨 pinkText -> pinkDarkText
  • 🚨 beige100 -> beigeSubtle
  • 🚨 beige200 -> beigeLight
  • 🚨 beige300 -> beige
  • 🚨 beige400 -> beigeMedium
  • 🚨 grey100 -> greySubtle
  • 🚨 grey200 -> greyLight
  • 🚨 grey300 -> grey
  • 🚨 grey400 -> greyMedium
• 🔄 changes in breakpoints group
  • 🟢 new small, medium, large breakpoints
  • 🚨 all old tokens are deprecated
• 🔄 changes in boxShadow group
  • 🟢 new thin, medium, thick, xthick tokens
  • 🚨 all old tokens are deprecated

Renamed and updated tokens groups

• 🔄 fontFamily -> fontFamilies
  • 🚨 tokens now contains whole CSS font stacks, no need to specify additional fallback fonts
• 🔄 fontSize -> fontSizes
  • 🚨 micro -> small
  • 🚨 small -> small
  • 🚨 base -> medium
  • 🚨 h6 -> small
  • 🚨 h5 -> small
  • 🚨 h4 -> medium
  • 🚨 h3 -> large
  • 🚨 h2 -> xlarge
  • 🚨 h1 -> xxlarge
  • 🟢 new huge token
• 🔄 fontWeight -> fontWeights
• 🔄 letterSpacings -> letterSpacing
  • 🚨 base -> default
  • 🚨 mediumHeading -> tight
  • 🚨 largeHeading -> tight
  • 🟢 new relaxed token
• 🔄 lineHeight -> lineHeights
  • in most cases, for headings use default token and for large amout of mid-sized text use relaxed
  • 🚨 base -> relaxed
  • 🚨 heading -> default
  • 🚨 largeHeading -> default
  • 🟢 new tight token